---
layout: docs
page_title: Client Count
description: Counting the number of clients accessing Vault.
---

# Client Count

The number of active clients using a Vault cluster is the total of:

- active entities: identity entities that create a token via a login
- active non-entity tokens: tokens created via a method that is not associated with an entity

Prior to Vault 1.6, this metric could only be measured from the audit log, using the
`vault-advisor` tool. Starting with Vault 1.6, the number of clients per month, or for
a contiguous sequence of months, can be measured by Vault itself.

Please refer to [Vault Usage Metrics](https://learn.hashicorp.com/tutorials/vault/usage-metrics) for a
step-by-step tutorial and description of how to use the UI.

## Measuring clients

Each time a token is created, Vault checks to see whether it belongs to an identity entity
that has already been active in the current month. New entities are added to a log in Vault storage
periodically. New tokens without entities are added to the "non-entity token" count.

At the end of each month, Vault creates precomputed reports listing the number of active entities,
per namespace, in each time period within a configurable retention period. This process deduplicates
entities by ID, so that if an entity is active within every calendar month, it still only counts as
one client for the entire year.

There are no client count metrics available until after the first calendar month finishes.

The client counts sum activity from all nodes in a cluster, including batch tokens created by performance
standby nodes. Performance secondary clusters have their own client population, and their own client metrics;
Vault does not aggregate or deduplicate clients across clusters. However, the logs and precomputed
reports are included in DR replication.

### Costs of measurement

Each active entity in the log consumes a few bytes of storage. Vault limits the number of identity
entities it records per month (to 656,000) as a safety measure to prevent unbounded storage growth. However,
typical storage costs should be much less. 1000 monthly active entities will require about 1.5 MiB of storage
capacity over the default 24-month retention period. A smaller amount of additional storage is used for
precomputed reports for all valid start/end pairs of months.

### Disabling measurement

To avoid this potentially unwanted storage usage, the client count feature can be disabled via the UI or API.
By default, the client count is disabled on open source builds, and enabled on Enterprise binaries. The CLI command
to change its state is:

```shell-session
# To enable
$ vault write sys/internal/counters/config enabled=enable

# To disable
$ vault write sys/internal/counters/config enabled=disable
```

If you disable the client counter, then all complete months and all precomputed reports will remain in storage
until their normal expiration time. This allows queries to be run on older data, even if no new data is being collected.

Vault does not report across a disable/enable cycle of the client count. All subsequent reports will start at the
time that the feature is enabled.

## Understanding Non-entity tokens

A token without an entity can be created in any of the following ways:

- A root token creates a token via `auth/token/create`.
- Any other token without an entity creates a child token via `auth/token/create` or a token role.
- An orphan token is created via `auth/token/create-orphan`; such a token does not inherit the entity of its creator.
- A token is created using a token role that specifies `orphan=true`.
- An auth method would normally create an entity, but is not allowed to do so, such as:
  - A batch token is created on a performance standby node.
  - A service token is created on a performance secondary replica, using a local mount.

The `entity_id` field will be empty, or show as `n/a`, for any token that is classified as a non-entity token:

```shell-session
$ vault token lookup
Key                 Value
---                 -----
entity_id           n/a
```

To reduce the number of non-entity tokens in use, consider switching to an authentication method such as
[AppRole](/docs/auth/approle) instead of handing out directly-created tokens. Ensure that entities and
[entity aliases](/api/secret/identity/entity-alias) exist for all login methods used to create batch tokens.

## API and Permissions

Please see [Client Count API](/api/system/internal-counters#client-count) for more details. Note that this API is marked as
"internal" so its behavior or format may change without warning. The UI is the preferred means of interacting with the
client count feature.

For the UI to be able to use the client count feature, it needs `read` permission to the following paths:

- `sys/internal/counters/activity`
- `sys/internal/counters/config`

For the UI to be able to modify the configuration settings, it additionally needs `update` permission to
`sys/internal/counters/config`.
